Summary

Doc-only — 1238-line architectural spec that supersedes the piecemeal A3 cleanup with a unified attack on three decomposition problems under ONE ACID test.

ACID test (the new load-bearing invariant):

For ANY new algorithm OR new backend target, the addition must be purely additive — zero edits to existing source files. Contribution = plugin (new typed ops + @lowering rules + @register_render registrations + entry-point declaration).

Today the redesign satisfies this for ~one slice of one target (per-MIR-op kernel-body @lowering on CUDA). It does NOT satisfy it for three other concerns.

The three problems addressed

1. Phase R — Runner monolith: orchestrator + complete_runner + runner = 2800 LOC of imperative CUDA-shaped scheduling. Becomes RIR (runner IR) + per-MIR-op @lowering rules + @register_render handlers.
2. Phase T — Target leakage into IR: IIR ops carry CUDA C++ shape (SaTiledCartesian2D op docstring IS the C++ template — it doesn't just encode the shape, it IS the shape). LoweringCtx holds ~15 CUDA-render scratch fields. Split into target-agnostic LowerCtx (5 fields, F3-pinned) + per-target CudaRenderCtx. Rename CUDA-shaped IIR ops to semantic names.
3. Phase B2 — Target monopolization: compile_kernel_body(ep, target='cuda') accepts the param but the rest of the pipeline hard-wires CUDA. Compiler.run(prog, target='cuda') + multi-target targets=['cuda', 'cpu_tbb']. Plugin discovery splits into [srdatalog.dialects] (data) + [srdatalog.targets] (render). R3 verify_renderability becomes per-target.

Biggest surprises uncovered during diagnosis

1. ep_has_X(...) helpers are the bool-field anti-pattern reskinned. The parked A3-1/2/3 branches replace if ep.dedup_hash: with if ep_has_pragma(ep, DedupHash): — same imperative branch, different key. Spec § 8.3 marks them as net-negative work post-redesign; Phase R deletes both bool reads AND helper reads in one shot.
2. complete_runner.py:37 literal cross-tree side-effect import to trigger CUDA plugin registration. Runner knows a specific data dialect by name. Worse coupling than the brief described.
3. LoweringCtx is more entangled than expected — actual count is 9 CUDA-identifier fields + 5 pragma-scratch flags (15 total), not the 5 listed in the brief. Plus legacy CodeGenContext has 35+ fields.
4. SaTiledCartesian2D has 20 fields and the op docstring IS the literal CUDA C++ template text at ops.py:196-232. Not "encodes CUDA shape" — IS the CUDA shape rendered into the type system.
5. view_counts_for_specs is consumed by EmitViewDeclsShim in the supposedly-target-agnostic kernel pipeline. Spec moves it into a CUDA-render-side pass.

Per-PR partition

Expanded to 35 PRs (vs estimated 20-30) to preserve per-PR byte-equivalence gating:

• Wave R1 framework (3) → R2 per-MIR-op lowerings (8) → R3 RIR renders (8)
• Wave T1 LoweringCtx split (2) → T2 IIR rename (5) → T3 index-plugin split (2)
• Wave B2-1 target param (3) → B2-2 multi-target (2)
• Cleanup (2)

Dependency that required care: T1 must precede R3 (RIR renders need per-target render-ctx); B2-1 must precede R3-8 (per-target render dispatch is what R3-8 deletes the monolith to use).

Framing tensions

1. Phase E retroactive versioning: Wave T3 splits each built-in dialect into data + per-target render contributions. Existing external plugins (jaccard demo External plugin demo: srdatalog_jaccard (proves third-party dialects via entry-point alone) #68) don't break (single register() form continues to work), but multi-target plugins need to split. Should Phase E be versioned E1 + E2? Spec recommends yes when Wave T3 lands; defers to reviewer.
2. D20 vs migration-period exemption: D20 (additive contract) would block 100% of the migration PRs themselves. Spec § 7 introduces GitHub-label-based exemption (feature: blocked; migration: / refactor: exempt). Procedural rather than mechanical.
3. Phase R brings in what original A3 spec called "out of scope" (WS runner integration). The new spec absorbs that work; parked A3 PRs are abandoned in favor of unified Phase R.

Relationship to existing work

• F1-F5 stay (foundation is correct; only dialect/codegen layers need decomposition)
• Phase A1-A2, B, C, D, E stay merged
• Phase A3 (parked branches A3-1/2/3 + open PR A3-2: remove deprecated work_stealing bool field (Layer 3 cleanup) #73) SUPERSEDED — bool field removals + ep_has_X(...) helpers both disappear under Phase R
• PR External plugin demo: srdatalog_jaccard (proves third-party dialects via entry-point alone) #68 jaccard demo stays as customizability proof; extended once per-target render dialect split lands
• PR Sorted-array terminal wrap-op registry — closes external-plugin dispatcher gap #72 dispatcher gap fix stays — framework infrastructure that's correct independent of Phase R/T/B2

Test plan

• sphinx -W build: clean
• ruff check + format (CI v0.9.10): clean
• (Doc-only; no code paths exercised)

Why this is a DRAFT

Open as draft so you can review the spec before any subsequent migration PR references it. Conversion to ready-for-review happens after you sign off on:

• The three-phase framing
• The 35-PR partition + ordering
• D20 + migration-label exemption shape
• The parked A3 work being abandoned (vs revived/finished)

🤖 Generated with Claude Code